home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / io / Reader.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  7.1 KB  |  221 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Reader.java    1.16 98/09/21
  3.  *
  4.  * Copyright 1996-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.io;
  16.  
  17.  
  18. /**
  19.  * Abstract class for reading character streams.  The only methods that a
  20.  * subclass must implement are read(char[], int, int) and close().  Most
  21.  * subclasses, however, will override some of the methods defined here in order
  22.  * to provide higher efficiency, additional functionality, or both.
  23.  *
  24.  * 
  25.  * @see BufferedReader
  26.  * @see   LineNumberReader
  27.  * @see CharArrayReader
  28.  * @see InputStreamReader
  29.  * @see   FileReader
  30.  * @see FilterReader
  31.  * @see   PushbackReader
  32.  * @see PipedReader
  33.  * @see StringReader
  34.  * @see Writer
  35.  *
  36.  * @version     1.16, 98/09/21
  37.  * @author    Mark Reinhold
  38.  * @since    JDK1.1
  39.  */
  40.  
  41. public abstract class Reader {
  42.  
  43.     /**
  44.      * The object used to synchronize operations on this stream.  For
  45.      * efficiency, a character-stream object may use an object other than
  46.      * itself to protect critical sections.  A subclass should therefore use
  47.      * the object in this field rather than <tt>this</tt> or a synchronized
  48.      * method.
  49.      */
  50.     protected Object lock;
  51.  
  52.     /**
  53.      * Create a new character-stream reader whose critical sections will
  54.      * synchronize on the reader itself.
  55.      */
  56.     protected Reader() {
  57.     this.lock = this;
  58.     }
  59.  
  60.     /**
  61.      * Create a new character-stream reader whose critical sections will
  62.      * synchronize on the given object.
  63.      */
  64.     protected Reader(Object lock) {
  65.     if (lock == null) {
  66.         throw new NullPointerException();
  67.     }
  68.     this.lock = lock;
  69.     }
  70.  
  71.     /**
  72.      * Read a single character.  This method will block until a character is
  73.      * available, an I/O error occurs, or the end of the stream is reached.
  74.      *
  75.      * <p> Subclasses that intend to support efficient single-character input
  76.      * should override this method.
  77.      *
  78.      * @return     The character read, as an integer in the range 0 to 16383
  79.      *             (<tt>0x00-0xffff</tt>), or -1 if the end of the stream has
  80.      *             been reached
  81.      *
  82.      * @exception  IOException  If an I/O error occurs
  83.      */
  84.     public int read() throws IOException {
  85.     char cb[] = new char[1];
  86.     if (read(cb, 0, 1) == -1)
  87.         return -1;
  88.     else
  89.         return cb[0];
  90.     }
  91.  
  92.     /**
  93.      * Read characters into an array.  This method will block until some input
  94.      * is available, an I/O error occurs, or the end of the stream is reached.
  95.      *
  96.      * @param       cbuf  Destination buffer
  97.      *
  98.      * @return      The number of bytes read, or -1 if the end of the stream
  99.      *              has been reached
  100.      *
  101.      * @exception   IOException  If an I/O error occurs
  102.      */
  103.     public int read(char cbuf[]) throws IOException {
  104.     return read(cbuf, 0, cbuf.length);
  105.     }
  106.  
  107.     /**
  108.      * Read characters into a portion of an array.  This method will block
  109.      * until some input is available, an I/O error occurs, or the end of the
  110.      * stream is reached.
  111.      *
  112.      * @param      cbuf  Destination buffer
  113.      * @param      off   Offset at which to start storing characters
  114.      * @param      len   Maximum number of characters to read
  115.      *
  116.      * @return     The number of characters read, or -1 if the end of the
  117.      *             stream has been reached
  118.      *
  119.      * @exception  IOException  If an I/O error occurs
  120.      */
  121.     abstract public int read(char cbuf[], int off, int len) throws IOException;
  122.  
  123.     /** Maximum skip-buffer size */
  124.     private static final int maxSkipBufferSize = 8192;
  125.  
  126.     /** Skip buffer, null until allocated */
  127.     private char skipBuffer[] = null;
  128.  
  129.     /**
  130.      * Skip characters.  This method will block until some characters are
  131.      * available, an I/O error occurs, or the end of the stream is reached.
  132.      *
  133.      * @param  n  The number of characters to skip
  134.      *
  135.      * @return    The number of characters actually skipped
  136.      *
  137.      * @exception  IOException  If an I/O error occurs
  138.      */
  139.     public long skip(long n) throws IOException {
  140.     if (n < 0L) 
  141.         throw new IllegalArgumentException("skip value is negative");
  142.     int nn = (int) Math.min(n, maxSkipBufferSize);
  143.     synchronized (lock) {
  144.         if ((skipBuffer == null) || (skipBuffer.length < nn))
  145.         skipBuffer = new char[nn];
  146.         long r = n;
  147.         while (r > 0) {
  148.         int nc = read(skipBuffer, 0, (int)Math.min(r, nn));
  149.         if (nc == -1)
  150.             break;
  151.         r -= nc;
  152.         }
  153.         return n - r;
  154.     }
  155.     }
  156.  
  157.     /**
  158.      * Tell whether this stream is ready to be read.
  159.      *
  160.      * @return True if the next read() is guaranteed not to block for input,
  161.      * false otherwise.  Note that returning false does not guarantee that the
  162.      * next read will block.
  163.      *
  164.      * @exception  IOException  If an I/O error occurs
  165.      */
  166.     public boolean ready() throws IOException {
  167.     return false;
  168.     }
  169.  
  170.     /**
  171.      * Tell whether this stream supports the mark() operation.
  172.      */
  173.     public boolean markSupported() {
  174.     return false;
  175.     }
  176.  
  177.     /**
  178.      * Mark the present position in the stream.  Subsequent calls to reset()
  179.      * will attempt to reposition the stream to this point.  Not all
  180.      * character-input streams support the mark() operation.
  181.      *
  182.      * @param  readAheadLimit  Limit on the number of characters that may be
  183.      *                         read while still preserving the mark.  After
  184.      *                         reading this many characters, attempting to
  185.      *                         reset the stream may fail.
  186.      *
  187.      * @exception  IOException  If the stream does not support mark(),
  188.      *                          or if some other I/O error occurs
  189.      */
  190.     public void mark(int readAheadLimit) throws IOException {
  191.     throw new IOException("mark() not supported");
  192.     }
  193.  
  194.     /**
  195.      * Reset the stream.  If the stream has been marked, then attempt to
  196.      * reposition it at the mark.  If the stream has not been marked, then
  197.      * attempt to reset it in some way appropriate to the particular stream,
  198.      * for example by repositioning it to its starting point.  Not all
  199.      * character-input streams support the reset() operation, and some support
  200.      * reset() without supporting mark().
  201.      *
  202.      * @exception  IOException  If the stream has not been marked,
  203.      *                          or if the mark has been invalidated,
  204.      *                          or if the stream does not support reset(),
  205.      *                          or if some other I/O error occurs
  206.      */
  207.     public void reset() throws IOException {
  208.     throw new IOException("reset() not supported");
  209.     }
  210.  
  211.     /**
  212.      * Close the stream.  Once a stream has been closed, further read(),
  213.      * ready(), mark(), or reset() invocations will throw an IOException.
  214.      * Closing a previously-closed stream, however, has no effect.
  215.      *
  216.      * @exception  IOException  If an I/O error occurs
  217.      */
  218.      abstract public void close() throws IOException;
  219.  
  220. }
  221.